<!-- DO NOT EDIT. This file generated from template by Code Scrawl https://tluf.me/php/code-scrawl/ -->
# Code Scrawl
Documentation Generation with `@verbs()` in markdown for special functionality and templates for common documentation needs. Define your own verbs & templates.
Integrated with [php/lexer](https://tluf.me/php/lexer) for ASTs of PHP classes (there may be bugs & it's tested only with php 7.4).
Run scrawl with `vendor/bin/scrawl` from your project root.
## Example `.docsrc/README.src.md`
See below for a list of templates & `@verbs` available to use.
This would display the `## Install` instructions and `## Configure` instructions as below
```md
# Code Scrawl
Intro text
## Install
@template(php/compose_install, taeluf/code-scrawl)
## Configure
Create a file `.config/scrawl.json` or `scrawl.json` in your project root. Defaults:
```
@file(src/defaults.json)
```
```
## Install
```bash
composer require taeluf/code-scrawl v0.8.x-dev
```
or in your `composer.json`
```json
{"require":{ "taeluf/code-scrawl": "v0.8.x-dev"}}
```
## Configure
Create a file `.config/scrawl.json` or `scrawl.json` in your project root. Defaults:
```php
{
"--comments":{
"Documentation": "Visit https://www.taeluf.com/docs/Code%20Scrawl or https://gitlab.com/taeluf/php/CodeScrawl",
"Deprecation 1":"Version 1.0 will scan src/ & test/ ",
"Deprecation 2":"Version 1.0 will default to non-hidden directories 'docsrc' and 'doctemplate'",
"Deprecation 3":"Version 1.0 will fully-default to 'config/' dir rather than '.config/', though both will still work.",
"Addition 1": "2023-12-23: Added 'api.output_dir = 'api/' config. If `null`, then do not write api output files. Previously, APIs were ALWAYS output to the api/ dir. Default config has the same behavior as before.",
"Addition 2": "2023-12-23: Add api.generate_readme config (default TRUE). This is NEW Functionality that creates a README in the api/ dir."
},
"template.dirs": [".doctemplate"],
"dir.docs": "docs",
"dir.src": ".docsrc",
"dir.scan": ["code", "test"],
"api.output_dir": "api/",
"api.generate_readme": true,
"ScrawlExtensions":[],
"file.bootstrap":"scrawl-bootstrap.php",
"deleteExistingDocs": false,
"readme.copyFromDocs": false,
"markdown.preserveNewLines": true,
"markdown.prependGenNotice": true
}
```
## Define your own verbs
In your `scrawl-bootstrap.php` file, do something like:
```php
<?php
/**
* @param $scrawl instance of `\Tlf\Scrawl`
*/
$scrawl->verb_handlers['own_verb'] =
function($arg1, $arg2){
return $arg1.'--'.$arg2;
};
```
## Write your own templates
Look at existing templates in [doctemplate/](/doctemplate/) or [src/Template](/src/Template) for examples.
## Run Scrawl
`cd` into your project root
```bash
# run documentation on the current dir
vendor/bin/scrawl
```
## File Structure (defaults)
- `.config/scrawl.json`: configuration file
- `.docsrc/*.src.md`: documentation source files (from which your documentation is generated)
- `docs/`: generated documentation output
- `code/*`, and `test/*`: Code files to scan
- `doctemplate/*.md.php` and `CodeScrawl/src/Template/*.md.php`: re-usable templates
- `scrawl-bootstrap.php`: Runs before `$scrawl->run()` and has access to `$scrawl` instance
## `@Verbs`
Write these in your markdown source files for special functionality
- `@import()`: Import something previously exported with `@export` or `@export_start/@export_end`. Usage: `@import(Namespace.Key)`
- `@file()`: Copy a file's content into your markdown.. Usage: `@file(rel/path/to/file.ext)`
- `@template()`: Load a template. Usage: `@template(template_name, arg1, arg2)`
- `@link()`: Output links configured in your config json file.
Config format is `{..., "links": { "link_name": "https://example.org"} }`. Usage: `@link(phpunit)`
- `@easy_link()`: Get a link to common services (twitter, gitlab, github, facebook). Usage: `@easy_link(twitter, TaelufDev)`
- `@hard_link()`: just returns a regular markdown link. In future, may check validity of link or do some kind of logging. Usage: `@hard_link(https://url.com, LinkName)`
- `@see_file()`: Get a link to a file in your repo. Usage: `@see_file(relative/file/path)`
- `@see()`: Get a link to a file in your repo. Usage: `@see_file(relative/file/path)`
- `@system()`: Run a command on the computer's operating system.
Supported options: `trim`, `trim_empty_lines`, `last_x_lines, int`
- `@ast()`: Get an ast & optionally load a custom template for it. Usage: `@ast(class.ClassName.methods.docblock.description, ast/default)`
## Templates
Templates can be loaded with `@template(template_name, arg1, arg2)`, though ast templates should be loaded with `@ast(class.ClassName.ast_path, ast/template_name)` where the template name is optional.
Click the link to view the template file to see the documentation on how to use it & what args it requires
## Exports (from code in scan dirs)
In a docblock, write `@export(Some.Key)` to export everything above it.
In a block of code (or literally anywhere), write `// @export_start(Some.Key)` then `// @export_end(Some.key)` to export everything in between.
See [test/run/SrcCode.php](/test/run/SrcCode.php) for examples
## More Info
- Run withOUT the cli: Some of the configs require absolute paths when running through php, rather than from the cli. An example is in [test/run/Integrate.php](/test/run/Integrate.php) under method `testRunFull()`
- `@literal`: Displaying a literal `@literal` in an md source file can be done by putting a [Zero Width Non-Joiner](https://unicode-explorer.com/c/200C) after the arroba (`@`). You can also use a backslash like so: `@\literal`, but then the backslash prints
- All classes in this repo: [docs/ClassList.md](/docs/ClassList.md)
- `$scrawl` has a `get/set` feature. In a template, you can get an ast like `$scrawl->get('ast.Fully\Qualified\ClassName')`. Outside a template, you can use the `Php` class ([src/Ext/Php.php](/src/Ext/Php.php)) to get an ast from a file or string.
- the `deleteExistingDocs` config has a bit of a sanity check to make sure you don't accidentally delete your whole system or something ...